'.\" t
.TH "drbd_tool" "1M" "Jun 27, 2006" "1\&.2\&.0"
.SH NAME
drbd_tool \- Linuxha.net DRBD Support Utility

.SH SYNOPSIS
.TS
l.
drbd_tool \fB--action=check --application X [args]\fP [\fB--nochecksums\fP]
          [\fB--vg\fP \fIvg\fP] [\fB--lv\fP \fIlv\fP]
          [\fB--logcmd\fP]
          Check that all DRBD devices for application are active

drbd_tool \fB--action=start\fP \fB--application\fP \fIapp\fP\fP [\fB--renew_on_standalone\fP]
          [\fB--protocol\fP \fIA|B|C\fP] [\fB--nochecksums\fP] [\fB--vg\fP \fIvg\fP] [\fB--lv\fP \fIlv\fP]
          [\fB--logcmd\fP] [\fB--noprimary\fP] [\fB--newonly\fP]
          Start required DRBD devices for application

drbd_tool \fB--action=set_primary\fP \fB--application\fP \fIapp\fP
          [\fB--force\fP] [\fB--nochecksums\fP] [\fB--vg\fP \fIvg\fP] [\fB--lv\fP \fIlv\fP]
          [\fB--logcmd\fP]
          Set the devices locally to be primary data copy

drbd_tool \fB--action=set_secondary\fP \fB--application\fP \fIapp\fP
          [\fB--force\fP] [\fB--nochecksums\fP] [\fB--vg\fP \fIvg\fP] [\fB--lv\fP \fIlv\fP]
          [\fB--logcmd\fP]
          Set the devices locally to be secondary data copy

drbd_tool \fB--action=down\fP \fB--application\fP \fIapp\fP
          [\fB--force\fP] [\fB--nochecksums\fP] [\fB--vg\fP \fIvg\fP] [\fB--lv\fP \fIlv\fP]
          [\fB--logcmd\fP]
          Take down local DRBD devices

drbd_tool \fB--action=disconnect\fP \fB--application\fP \fIapp\fP
          [\fB--nochecksums\fP] [\fB--vg\fP \fIvg\fP] [\fB--lv\fP \fIlv\fP]
          [\fB--logcmd\fP]
          Take down connection to remote devices

drbd_tool \fB--action=set_rate\fP \fB--application\fP \fIapp\fP \fB--rate\fP \fINum\fP
          [\fB--nochecksums\fP] [\fB--vg\fP \fIvg\fP] [\fB--lv\fP \fIlv\fP]
          [\fB--logcmd\fP]
          Set the maximum synchronisation rate per device

drbd_tool \fB--action=invalidate\fP \fB--application\fI \fIapp\fP
          [\fB--nochecksums\fP] [\fB--vg\fP \fIvg\fP] [\fB--lv\fP \fIlv\fP]
          [\fB--logcmd\fP] [\fB--timeout\fP \fIsecs\fP]
          Invalidate specified or all local copies

drbd_tool \fB--action=invalidate_remote\fP \fB--application\fP \fIapp\fP
          [\fB--nochecksums\fP] [\fB--vg\fP \fIvg\fP] [\fB--lv\fP \fIlv\fP]
          [\fB--logcmd\fP]
          Invalidate specified or all remote copies

drbd_tool \fB--action=force_invalidate\fP \fB--application\fP \fIapp\fP
          [\fB--force\fP] [\fB--nochecksums\fP] [\fB--vg\fP \fIvg\fP] [\fB--lv\fP \fIlv\fP]
          [\fB--logcmd\fP] [\fB--timeout\fP \fIsecs\fP]
          Forces local data copy to be invalid

drbd_tool \fB--action=reconnect\fP \fB--application\fP \fIapp\fP
          [\fB--protocol\fP \fIA|B|C\fP] [\fB--nochecksums\fP] [\fB--vg\fP \fIvg\fP] [\fB--lv\fP \fIlv\fP]
          [\fB--logcmd\fP]
          Perform disconnect/reconnect sequence if possible

drbd_tool \fB--action=resize\fP \fB--application\fP \fIapp\fP
          [\fB--nochecksums\fP] [\fB--vg\fP \fIvg\fP] [\fB--lv\fP \fIlv\fP]
          [\fB--logcmd\fP]
          Indicate online resize of specified DRBD device

drbd_tool \fB-?\fP
        Show brief usage information
.TE

.SH DESCRIPTION
This utility attempts to perform any necessary actions on the local DRBD
devices, such as making them available, or taking them down. The utility
works on a per-application basis taking account of the resources 
allocated to the application in question.

All interaction with the DRBD userspace tools takes place via this
utility, though the 'fsmonitor' Lems module also make use of the 
proc/drbd special file to get status information when requested.

.SH SUPPORTED ACTIONS
The \fB--action\fP argument must be specified to ensure that a certain
action must take place. As stated in the synopsis the following actions
are supported.

.TS
l l.
check	Check to see if the specified devices for the 
	application are correctly configured.
start	Ensure the devices for the specified application are 
	started or restarted (depending on supplied 
	arguments).
set_primary	Indicates the local copy is primary and can be
	mounted.
set_secondary	Indicates the local copy is secondary (will not be
	mounted or used).
down	Take down the local DRBD devices so they are 
	essentially classed as 'unconfigured'.
disconnect	Stop the connection to the remote node. Any 
	subsequent writes will cause a resynchronisation
	event when both devices connect again.
set_rate	Specified the maximum synhronisation rate that 
	should be used - specified in Kb/second.
invalidate	Indicate that the local devices specified should be 
	forced to to 'stale' if possible.
invalidate_remote	Indicate that the remote devices specified should be
	forced to to 'stale' state if possible.
force_invalidate	Causes the local copy to become stale.
reconnect	Attempt a reconnection of the specified devices.
resize	Indicate DRBD should re-assess size of specified 
	devices.
.TE

The action will always require the \fB--application\fP argument, though
others are also available.

.SH ARGUMENTS
Apart from the \fB--action\fP argument the following arguments are
supported.

.TP 8
.B --application
Indicates the name of the application to which the action applies. The
application must have been successfully built using the \fIclbuildapp(1M)\fP
utility - and should have valid checksums available.
.TP
.B --newonly
When the \fBstart\fB action has been specified the default action if any
device is already discerned is to in a \fBdown\fP state then start it.
Without this option the 'start' action will down any existing connections
and restart them, rather than just starting 'new' devices.
.TP
.B --timeout
Used to indicate how long \fIdrbd_tool(1M)\fP should wait for the DRBD device
to enter the required state before aborting. If not specified it will
default to 10 seconds.
.TP
.B --noprimary
Indicates that the devices should be started not as primary devices - if 
this is not specified it detaults to starting the devices as primary (i.e.
ready to mount on the local machine).
.TP
.B --force
The specified action is forced to take place - even if the underlying
DRBD device thinks it is a bad idea. \fBUSE WITH CAUTION.\fP
.TP
.B --vg
This must be combined with the \fB--lv\fP argument and indicates the
command should be run against a specific device only. This is useful
when adding or removing a new file system to an application that is
currently running in the cluster.
.TP
.B --lv
This is combined with the \fB--vg\fP argument and is used to ensure that
the specified action is carried out against just a specified logical 
volume rather than all logical volumes for the given application.
.TP
.B --logcmd
Any of the external commands used are included in the verbose output - so 
must be also combined with \fB--verbose\fP to actually see the commands.
.TP
.B --rate
This argument must be specified when the requried action is \fBset_rate\fP. 
It indicates the maximum synchronisation rate for each device that
requires synchronisation. Please note that this value is \fBper device\fP,
so if lots of devices require synchronisation the effect of I/O on each of
the servers will be more apparent.
.TP
.B --protocol
Indicates the DRBD protocol to use between the two nodes. The default and
recommended value (for the sake of data sanity) is protocol 'C', though this
can be set to 'B' or indeed 'A'. \fBOnly change this setting if you are
really certain of what you are doing.\fP
.TP
.B --nochecksums
Force the action to occur against the specified application even if the
checksums that validate the \fIclbuildapp(1M)\fP utility has been run
successfully do not appear to match.
.TP
.B --renew_on_standalone
This flag only has an affect when the action specified is 'start'. For
each device that is currently running it will attempt to perform a
'disconnect' from the remote copy. This only occurs if the device is not
currently defined, or is defined but not in a 'connected' state.

Following that it does not attempt to define the local block device, but
moves on to the remote connectivity part of device definition.

Although odd this functionality is optionally used for the \fBNDB_START\fP
request sent to the cluster daemon by the fsmonitor Lems module under
certain connections.
parameters for the device
.TP
.B --config
Allows an alternative cluster configuration file to be used, rather than the 
default - /etc/cluster/clconf.xml. Mainly used for debugging and development
purposes.

.SH EXIT STATUS
The \fIlvmtool(1M)\fP utility typically only makes use of two exit codes:

.TP 4
0
The requested operation has been completed successfully.
.TP
1
An error occured whilst trying to perform the specified operation.

.SH SEE ALSO
.TS
l l.
drbdsetup(1M)	- Create and manipulate drbd devices
.TE

.SH AUTHOR
The \fIdrbd_tool(1M)\fP utility was written by Simon Edwards, 2004-2006. The
author can be contacted via the website mentioned below.

.SH AVAILABILITY
This software is freely available from the Linuxha.net website - please see
\fBhttp://www.linuxha.net\fP for more details.

.SH WARRANTY
This is Open Source Software is per the GNU GPL. It is free to use and
distribute but \fIcomes with no warranty whatsoever\fP. For more information
on the license please see \fBwww.gnu.org/copyleft/gpl.html\fP.

